快速入門 ¶

Yii 提供一整套工具來簡化實作 RESTful Web Service API 的任務。特別是，Yii 支援關於 RESTful API 的以下功能

• 快速原型設計，支援 Active Record 的常用 API；
• 回應格式協商（預設支援 JSON 和 XML）；
• 可自訂的物件序列化，支援可選的輸出欄位；
• 正確格式化集合資料和驗證錯誤；
• 集合分頁、過濾和排序；
• 支援 HATEOAS；
• 使用正確的 HTTP 動詞檢查進行高效路由；
• 內建支援 OPTIONS 和 HEAD 動詞；
• 身份驗證和授權；
• 資料快取和 HTTP 快取；
• 速率限制；

在下面，我們使用一個範例來說明如何以最少的程式碼工作量建構一組 RESTful API。

假設您想要透過 RESTful API 公開使用者資料。使用者資料儲存在 user 資料庫表格中，並且您已經建立了 active record 類別 app\models\User 以存取使用者資料。

建立控制器 ¶

首先，建立一個 控制器 類別 app\controllers\UserController 如下

namespace app\controllers;

use yii\rest\ActiveController;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
}

控制器類別繼承自 yii\rest\ActiveController，它實作了一組通用的 RESTful 行動。透過將 modelClass 指定為 app\models\User，控制器就知道可以使用哪個模型來提取和操作資料。

設定 URL 規則 ¶

然後，修改應用程式組態中 urlManager 組件的組態

'urlManager' => [
    'enablePrettyUrl' => true,
    'enableStrictParsing' => true,
    'showScriptName' => false,
    'rules' => [
        ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
    ],
]

上面的組態主要為 user 控制器新增一個 URL 規則，以便可以使用漂亮的 URL 和有意義的 HTTP 動詞來存取和操作使用者資料。

注意：Yii 將自動將控制器名稱複數化以用於端點（請參閱下面的試用看看章節）。您可以使用 yii\rest\UrlRule::$pluralize 屬性來組態此行為。

啟用 JSON 輸入 ¶

為了讓 API 接受 JSON 格式的輸入資料，請組態 request 應用程式組件 的 parsers 屬性，以使用 yii\web\JsonParser 進行 JSON 輸入

'request' => [
    'parsers' => [
        'application/json' => 'yii\web\JsonParser',
    ]
]

資訊：上面的組態是選用的。如果沒有上面的組態，API 將僅識別 application/x-www-form-urlencoded 和 multipart/form-data 輸入格式。

試用看看 ¶

透過上述最少的工作量，您已經完成了建立 RESTful API 以存取使用者資料的任務。您已建立的 API 包括

• GET /users：逐頁列出所有使用者；
• HEAD /users：顯示使用者列表的概觀資訊；
• POST /users：建立新使用者；
• GET /users/123：傳回使用者 123 的詳細資訊；
• HEAD /users/123：顯示使用者 123 的概觀資訊；
• PATCH /users/123 和 PUT /users/123：更新使用者 123；
• DELETE /users/123：刪除使用者 123；
• OPTIONS /users：顯示關於端點 /users 的支援動詞；
• OPTIONS /users/123：顯示關於端點 /users/123 的支援動詞。

您可以使用類似以下的 curl 命令來存取您的 API，

$ curl -i -H "Accept:application/json" "https://127.0.0.1/users"

HTTP/1.1 200 OK
...
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://127.0.0.1/users?page=1>; rel=self, 
      <http://127.0.0.1/users?page=2>; rel=next, 
      <http://127.0.0.1/users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

[
    {
        "id": 1,
        ...
    },
    {
        "id": 2,
        ...
    },
    ...
]

嘗試將可接受的內容類型變更為 application/xml，您將看到結果以 XML 格式傳回

$ curl -i -H "Accept:application/xml" "https://127.0.0.1/users"

HTTP/1.1 200 OK
...
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://localhost/users?page=1>; rel=self, 
      <http://localhost/users?page=2>; rel=next, 
      <http://localhost/users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <item>
        <id>1</id>
        ...
    </item>
    <item>
        <id>2</id>
        ...
    </item>
    ...
</response>

以下命令將透過傳送具有 JSON 格式使用者資料的 POST 請求來建立新使用者

$ curl -i -H "Accept:application/json" -H "Content-Type:application/json" \
    -XPOST "https://127.0.0.1/users" \
    -d '{"username": "example", "email": "user@example.com"}'

HTTP/1.1 201 Created
...
Location: http://127.0.0.1/users/1
Content-Length: 99
Content-Type: application/json; charset=UTF-8

{"id":1,"username":"example","email":"user@example.com","created_at":1414674789,"updated_at":1414674789}

提示：您也可以透過在 Web 瀏覽器中輸入 URL https://127.0.0.1/users 來存取您的 API。但是，您可能需要一些瀏覽器外掛程式來傳送特定的請求標頭。

如您所見，在回應標頭中，有關於總計數、頁面計數等資訊。還有一些連結可讓您導覽到其他資料頁面。例如，https://127.0.0.1/users?page=2 將為您提供下一頁使用者資料。

使用 fields 和 expand 參數，您也可以指定結果中應包含哪些欄位。例如，URL https://127.0.0.1/users?fields=id,email 將僅傳回 id 和 email 欄位。

資訊：您可能已經注意到 https://127.0.0.1/users 的結果包含一些敏感欄位，例如 password_hash、auth_key。您當然不希望這些出現在您的 API 結果中。您可以而且應該從結果中移除這些欄位，如資源章節中所述。

此外，您可以對集合進行排序，例如 https://127.0.0.1/users?sort=email 或 https://127.0.0.1/users?sort=-email。可以使用資料過濾器實作過濾集合，例如 https://127.0.0.1/users?filter[id]=10 或 https://127.0.0.1/users?filter[email][like]=gmail.com。有關詳細資訊，請參閱過濾集合章節。

自訂列表中的分頁和排序 ¶

為了變更模型列表的預設分頁和排序，您可以組態控制器中的 yii\rest\IndexAction。例如

<?php
namespace app\controllers;

use yii\rest\ActiveController;
use yii\helpers\ArrayHelper;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
    
    public function actions()
    {
        return ArrayHelper::merge(parent::actions(), [
            'index' => [
                'pagination' => [
                    'pageSize' => 10,
                ],
                'sort' => [
                    'defaultOrder' => [
                        'created_at' => SORT_DESC,
                    ],
                ],
            ],
        ]);
    }
}

有關如何組態 ActiveController 的操作的更多資訊，請參閱擴展 ActiveController。

總結 ¶

使用 Yii RESTful API 框架，您可以根據控制器操作來實作 API 端點，並且您可以使用控制器來組織實作單一資源類型端點的操作。

資源表示為從 yii\base\Model 類別擴展的資料模型。如果您正在使用資料庫（關聯式或 NoSQL），建議您使用 ActiveRecord 來表示資源。

您可以使用 yii\rest\UrlRule 來簡化到您的 API 端點的路由。

雖然不是必需的，但建議您將 RESTful API 開發為一個獨立的應用程式，與您的 Web 前端和後端不同，以便於維護。